Over-the-Air (OTA) Firmware Updates
Who should read these docs?
Firmware engineers implementing over-the-air firmware update handling on the device.
An OTA update delivers a new firmware image to a provisioned device. The platform is designed around multiple delivery channels, and the one built today is direct-to-cloud: the platform announces the update as an AWS IoT Job over the device's own MQTT connection, the device downloads the image over mutually-authenticated TLS (mTLS), verifies its integrity, and reports the outcome back through the Jobs API.
These docs describe the direct-to-cloud channel end to end. The Firmware Update Jobs page is the step-by-step implementation guide: MQTT topics, the job document contract, the mTLS download, and status reporting. This page covers the concepts and the cloud-side flow so you know what is happening on the other end. Future channels for tools without their own cloud connection are outlined in Relayed Delivery; that page is a placeholder until the channel is built.
How an Update Reaches a Device (Direct-to-Cloud)
- A firmware image is registered in the platform's package catalog. The image bytes live in a private S3 bucket fronted by a CloudFront CDN (content distribution network).
- An authorized operator (the CPP team, or a service acting on their behalf) creates a rollout: a tracked intent to deliver one package to a set of target devices.
- The platform creates an AWS IoT Job targeting those devices. The job persists until each device comes online and processes it.
- The device discovers the job through the standard AWS Jobs MQTT Topics, downloads the image from the firmware distribution endpoint using its operational certificate as the mTLS client identity, verifies the download against the size and SHA-256 checksum in the job document, and reports
SUCCEEDEDorFAILED.
The device never talks to the rollout APIs. Everything the device needs arrives in the job document from AWS IoT Core.
Key Concepts
| Concept | What it is |
|---|---|
| Package | One firmware image/bundle, uniquely identified by productId + firmwarePart + version + revision (e.g. product 0x012F, part main-mcu, version 1.3.2, revision 7). version is semver; revision is an incrementing build counter. |
| Rollout | A request to deliver one package to a set of devices (up to 100 per rollout). Each rollout creates exactly one IoT Job, and the IoT job ID equals the rolloutId. |
| Assignment | The platform's per-device delivery record for a rollout. Cloud-internal bookkeeping; the device never sees it. |
A device is targeted by its MPBID, which is also its IoT Thing name.
One Rollout at a Time
A device only ever has one live firmware delivery. When a new rollout targets a device that already has an undelivered update pending, the platform supersedes the older one and revokes its queued job execution. From the device's perspective a previously seen job can simply disappear from the pending queue; this is normal, and the replacement job carries the newer firmware.
Delivery Channels
A rollout targets devices, not transports. How the update physically reaches a device is a delivery channel, and the platform is built so more channels can be added without changing what the device receives:
| Channel | How it works | Status |
|---|---|---|
| Direct-to-cloud (AWS IoT Jobs) | The device has its own MQTT connection to the platform. The update arrives as an IoT Job and the device downloads the image itself over mTLS. | Built. Documented in Firmware Update Jobs. |
| Relayed (BLE) | A nearby relay (a gateway device or the ONE-KEY app) fetches the image and job document on behalf of a tool that has no cloud connection of its own, and forwards them over BLE. | Planned. Placeholder at Relayed Delivery. |
The job document is deliberately channel-agnostic: it contains everything needed to fetch and verify the image without consulting the Jobs API again, so the same document can travel over any channel. This is also why it carries a rolloutId field rather than an IoT job ID.
Relationship to Certificate Rotation
Firmware update jobs and platform-triggered certificate rotation jobs share the same discovery mechanics and can be queued for a device simultaneously. All CPP job types are dispatched on the operation field in the job document (firmware-update vs rotate-certificate), and a device must inspect a job's document before claiming it. See Handling Multiple Job Types for the required pattern.
The operational certificate the device uses for MQTT is the same credential used as the mTLS client identity for the firmware download. A device with an expired or revoked operational certificate must complete rotation before it can download firmware.